PATH Hardware Documentation > Device Managers and Drivers > ATA Devices > ATA Device Software Guide

ATA_DrvrRegister

The ATA_DrvrRegister function registers the driver reference number passed in for the selected drive. The function doesn't check for the existence of another driver. Any active driver that controls one or more devices through the ATA Manager must register with the manager to insure proper operation and notification of events. The first driver to register for the device gets the device. All subsequent registrations for the device are rejected.

The manager function code for the ATA_DrvrRegister function is $85.

The parameter block associated with ataPBVers of 1 is defined below:

typedef		struct	/* Driver registration */ /* structure for ataPBVers 1 */
{
	ataPBHdr		/* ataPBHdr parameter block */
	SInt16	drvrRefNum;	/* --> Driver reference number */
	UInt16	FlagReserved;	/* Reserved (should be zero)*/
	UInt16	deviceNextID;	/* Not used */
	SInt16	Reserved[21];	/* Reserved */
} ataDrvrRegister;

Field descriptions

ataPBHdr

See the definition of the ataPBHdr parameter block.

drvrRefNum

This field specifies the driver reference number to be registered. This value must be less than 0 to be valid.

FlagReserved

Reserved.

deviceNextID

Not used by this function.

Reserved[21]

This field is reserved. To ensure future compatibility, all reserved fields should be set to 0.

The parameter block associated with ataPBVers of 2 or greater is defined below:

typedef		struct	/* Driver registration */ /* structure for ataPBVers 2 */ /* or greater */
{
	ataPBHdr		/* ataPBHdr parameter block */
	SInt16	drvrRefNum;	/* --> Driver reference number */
	UInt16drvr	Flags;	/* --> Driver flags, set to 0 */
	UInt16	deviceNextID;	/* Not used */
	SInt16	Reserved;	/* Reserved (should be 0) */
	ProcPtr	ataEHandlerPtr;	/* --> Event handler routine */ /* pointer */
	SInt32	drvrContext;	/* --> Value to pass in with */ /* event handler */
	UInt32	ataEventMask;	/* --> Masks of various events */ /* for event handlers */
	SInt16	Reserved[14];	/* Reserved */
} ataDrvrRegister;

The version 2 parameter block also allows another type of registration; "notify-all" driver registration. The "notify-all" driver registration is identified by a value of -1 in the deviceID field of the header and bit 0 of drvrFlags set to 0. The "notify-all" driver registration is used if notification of all device insertions is desired. Registered default drivers are called if no media driver is found on the media. Typically, an INIT driver registers as a "notify-all" driver. The single driver may register as a "notify-all" driver, and then later, register for one or more devices on the bus.

Note
All PCMCIA/ATA and notify-all device drivers must register using the parameter block version 2 and utilize the event handling capability in order to insure proper operation. See the description of the ataEHandlerPtr, driverContent, and ataEventMask fields for additional information related to event handling.

Field descriptions

ataPBHdr

See the definition of the ataPBHdr parameter block.

drvrRefNum

This field specifies the driver reference number to be registered. This value must be less than 0 to be valid.

drvrFlags

No bit definition has been defined for the field. This field shall be set to 0 in order to insure compatibility in the future.

deviceNextID

Not used by this function.

Reserved

Reserved.

ataEHandlerPtr

A pointer to event handler routine for the driver. This routine is called whenever an event happens, and the mask bit for the particular event is set in the ataEventMask field.

The calling convention for the event handler is as follows:

pascal SInt16 (ataEHandlerPtr) (ATAEventRec*);

where ATAEventRec is defined as follows:

typedef		struct
{
	UInt16	evenCode;	/* ATA event code */
	UInt16	phyDrvRef;	/* ID associated with */ /* the event */
	SInt32	drvrContext;	/* Context passed in by */ /* the driver */
} ATAEventRec;

drvrContext

A value to be passed in when the event handler is called. This value is loaded in the ATAEventRec before calling the event handler.

ataEventMask

The mask defined in this field is used to indicate whether the event handler should be called or not, based on the event. The event handler is only called if the mask for the event has been set (1). If the mask is not set (0) for an event, the ATA Manager takes no action. The following masks have been defined:

Bits	Event mask
0x00	Null event
0x01	Online event - indicates an ATA or ATAPI device is available for use. This event occurs when a new device is connected to the bus or when a previously unavailable deviec becomes available again, such as after a system wakeup when power is restored to the device. If the device has a registered driver, only that driver will be notified of the event. Otherwise, each registered default driver will be notified until a driver responds with a noErr to the event. For a newly connected device, the driver loaded from the device media has priority. Device drivers should keep track of whether or not the device coming online is a newly connected device or one that is currently offline, but connected. A device should be considered connected until a device removed event (0x03) for the device occurs.
0x02	Offline event - a device has gone offline. This event notifies the registered driver of an ATA or ATAPI device that the device is offline and unavailable for use. The device is however still connected to the bus and the state is considered to be temporary. This event is sent at system sleep when the power is removed from the device. The event is curretly sent only when the ATA Manager receives a PM_SUSPEND event from the PC Card Manager. Drivers receiving offline events should maintain control of the device but deny access to the device from its clients. When the device is available again, an Online event is received, it may be necessary to reconfigure the device.
0x03	Device removed event - a device has been removed. This event notifies the registered driver of an ATA or ATAPI device that the device has been removed. The removal may be either controlled, such as a software eject, or uncontrolled, such as a forced removal by the user. The device may have been online or offline before the removal. If the device was online before the removal, an offline event is not generated, since the removal implies that an offline condition had to occur.
0x04	Reset event - a device has been reset. This event notifies the registered driver of an ATA or ATAPI device that the device has been reset. The device may need to be reconfigured by the driver before it can be used again. This event is for use with multiple devices on one bus, such as a ATA master/slave configuration. The Apple ATA implementation doesn't currently support multiple devices on a bus, therefore this event is not used. However, it is recommended that drivers support this event to ensure future compatibility when the event is implemented.
0x05	Offline request event - a request to put the device offline has been detected. This event is now obsolete. The funtion of this event was similar to a sleep request event. However, the current PC Card Manager allows only for an event like a sleep demand event, which does not permit rejection by the client.
0x06	Eject request event - a request to eject a device has been detected. This event notifies the driver of an ATA or ATAPI device that a request has been made to eject the device. If the response to the request is 0, the device is ejected and a subsequent Device Removed event (0x03) will be generated. The Eject request event acts as a protection mechanism to alert drivers of a pending ejecttion. A driver will generally want to reject the request unless they actually initiated it, since the ejection removes the device from the bus.
0x07	Configuration update event - the system configuration has changed (more devices)
0x08-0x1F	Reserved

 

Reserved[21]

This field is reserved. To ensure future compatibility, all reserved fields should be set to 0.

RESULT CODES

See Table A-1 for possible result codes returned by the ATA Manager.

Previous | Back Up One Level | Next | Show Frames | Hide Frames